package it.unicam.cs.cosy.bioshape.core.components.movers;

import it.unicam.cs.cosy.bioshape.core.components.Entity;
import it.unicam.cs.cosy.bioshape.core.components.ShapedEntity;

import java.io.Serializable;

import javax.vecmath.Vector3d;

/**
 * Defines the generic driving policy for an entity. An instance of implementing
 * classes is associated with each entity.
 * 
 * @author Federico Buti
 */
public interface EntityDriver extends Serializable {

	/**
	 * @param data
	 *            information necessary to calculate the new instant velocity
	 * @return a {@code Vector3d} representing the new instant velocity
	 */
	public Vector3d calculateNewInstantVelocity(Object[] data);

	/**
	 * Calculates the next instant angular velocity pseudovector for the associated
	 * {@code Entity}.<br>
	 * N.B.: The angular velocity <i>must<i> always be expressed in
	 * {@code radians}. Since the input is given in {@code degrees}, an explicit
	 * conversion is always needed. Indeed, the method
	 * {@code Entity#setInstantAngularVelocity(Vector3d instantAngularVelocity)} 
	 * <i>imposes</i> in its contract
	 * that the passed vector is expressed in radians since it does not apply
	 * any conversion from degrees to radians. The same applies to the method
	 * {@code Entity#updateVelocity()}. Hence, particular care must be put in
	 * implementing the {@code Entity} interface.
	 * 
	 * @param data
	 *            information necessary to calculate the new rotation
	 * 
	 * @return the rotation in radiant/seconds as a <i>pseudovector</i>.
	 * 
	 * @see "http://en.wikipedia.org/wiki/Pseudovector"
	 * @see Entity
	 * @see ShapedEntity
	 */
	public Vector3d calculateNewInstantAngularVelocity(Object[] data);
}
